<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>GCancellable</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
<link rel="home" href="index.html" title="GIO Reference Manual">
<link rel="up" href="async.html" title="Asynchronous I/O">
<link rel="prev" href="async.html" title="Asynchronous I/O">
<link rel="next" href="GAsyncResult.html" title="GAsyncResult">
<meta name="generator" content="GTK-Doc V1.17 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
<tr valign="middle">
<td><a accesskey="p" href="async.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="async.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">GIO Reference Manual</th>
<td><a accesskey="n" href="GAsyncResult.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr>
<tr><td colspan="5" class="shortcuts">
<a href="#GCancellable.synopsis" class="shortcut">Top</a>
                   | 
                  <a href="#GCancellable.description" class="shortcut">Description</a>
                   | 
                  <a href="#GCancellable.object-hierarchy" class="shortcut">Object Hierarchy</a>
                   | 
                  <a href="#GCancellable.signals" class="shortcut">Signals</a>
</td></tr>
</table>
<div class="refentry">
<a name="GCancellable"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle"><a name="GCancellable.top_of_page"></a>GCancellable</span></h2>
<p>GCancellable — Thread-safe Operation Cancellation Stack</p>
</td>
<td valign="top" align="right"></td>
</tr></table></div>
<div class="refsynopsisdiv">
<a name="GCancellable.synopsis"></a><h2>Synopsis</h2>
<pre class="synopsis">
#include &lt;gio/gio.h&gt;

                    <a class="link" href="GCancellable.html#GCancellable-struct" title="GCancellable">GCancellable</a>;
<a class="link" href="GCancellable.html" title="GCancellable"><span class="returnvalue">GCancellable</span></a> *      <a class="link" href="GCancellable.html#g-cancellable-new" title="g_cancellable_new ()">g_cancellable_new</a>                   (<em class="parameter"><code><span class="type">void</span></code></em>);
<a href="./../glib/glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="GCancellable.html#g-cancellable-is-cancelled" title="g_cancellable_is_cancelled ()">g_cancellable_is_cancelled</a>          (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>);
<a href="./../glib/glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="GCancellable.html#g-cancellable-set-error-if-cancelled" title="g_cancellable_set_error_if_cancelled ()">g_cancellable_set_error_if_cancelled</a>
                                                        (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>,
                                                         <em class="parameter"><code><a href="./../glib/glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);
<span class="returnvalue">int</span>                 <a class="link" href="GCancellable.html#g-cancellable-get-fd" title="g_cancellable_get_fd ()">g_cancellable_get_fd</a>                (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>);
<a href="./../glib/glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="GCancellable.html#g-cancellable-make-pollfd" title="g_cancellable_make_pollfd ()">g_cancellable_make_pollfd</a>           (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>,
                                                         <em class="parameter"><code><a href="./../glib/glib/glib-The-Main-Event-Loop.html#GPollFD"><span class="type">GPollFD</span></a> *pollfd</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="GCancellable.html#g-cancellable-release-fd" title="g_cancellable_release_fd ()">g_cancellable_release_fd</a>            (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>);
<a href="./../glib/glib/glib-The-Main-Event-Loop.html#GSource"><span class="returnvalue">GSource</span></a> *           <a class="link" href="GCancellable.html#g-cancellable-source-new" title="g_cancellable_source_new ()">g_cancellable_source_new</a>            (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>);
<a href="./../glib/glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            (<a class="link" href="GCancellable.html#GCancellableSourceFunc" title="GCancellableSourceFunc ()">*GCancellableSourceFunc</a>)           (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>,
                                                         <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);
<a class="link" href="GCancellable.html" title="GCancellable"><span class="returnvalue">GCancellable</span></a> *      <a class="link" href="GCancellable.html#g-cancellable-get-current" title="g_cancellable_get_current ()">g_cancellable_get_current</a>           (<em class="parameter"><code><span class="type">void</span></code></em>);
<span class="returnvalue">void</span>                <a class="link" href="GCancellable.html#g-cancellable-pop-current" title="g_cancellable_pop_current ()">g_cancellable_pop_current</a>           (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="GCancellable.html#g-cancellable-push-current" title="g_cancellable_push_current ()">g_cancellable_push_current</a>          (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="GCancellable.html#g-cancellable-reset" title="g_cancellable_reset ()">g_cancellable_reset</a>                 (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>);
<a href="./../glib/glib/glib-Basic-Types.html#gulong"><span class="returnvalue">gulong</span></a>              <a class="link" href="GCancellable.html#g-cancellable-connect" title="g_cancellable_connect ()">g_cancellable_connect</a>               (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>,
                                                         <em class="parameter"><code><a href="./../gobject/gobject/gobject-Closures.html#GCallback"><span class="type">GCallback</span></a> callback</code></em>,
                                                         <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>,
                                                         <em class="parameter"><code><a href="./../glib/glib/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> data_destroy_func</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="GCancellable.html#g-cancellable-disconnect" title="g_cancellable_disconnect ()">g_cancellable_disconnect</a>            (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>,
                                                         <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gulong"><span class="type">gulong</span></a> handler_id</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="GCancellable.html#g-cancellable-cancel" title="g_cancellable_cancel ()">g_cancellable_cancel</a>                (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>);
</pre>
</div>
<div class="refsect1">
<a name="GCancellable.object-hierarchy"></a><h2>Object Hierarchy</h2>
<pre class="synopsis">
  <a href="./../gobject/gobject/gobject-The-Base-Object-Type.html#GObject">GObject</a>
   +----GCancellable
</pre>
</div>
<div class="refsect1">
<a name="GCancellable.signals"></a><h2>Signals</h2>
<pre class="synopsis">
  "<a class="link" href="GCancellable.html#GCancellable-cancelled" title='The "cancelled" signal'>cancelled</a>"                                      : <a href="./../gobject/gobject/gobject-Signals.html#G-SIGNAL-RUN-LAST:CAPS"><code class="literal">Run Last</code></a>
</pre>
</div>
<div class="refsect1">
<a name="GCancellable.description"></a><h2>Description</h2>
<p>
GCancellable is a thread-safe operation cancellation stack used 
throughout GIO to allow for cancellation of synchronous and
asynchronous operations.
</p>
</div>
<div class="refsect1">
<a name="GCancellable.details"></a><h2>Details</h2>
<div class="refsect2">
<a name="GCancellable-struct"></a><h3>GCancellable</h3>
<pre class="programlisting">typedef struct _GCancellable GCancellable;</pre>
<p>
Allows actions to be cancelled.
</p>
</div>
<hr>
<div class="refsect2">
<a name="g-cancellable-new"></a><h3>g_cancellable_new ()</h3>
<pre class="programlisting"><a class="link" href="GCancellable.html" title="GCancellable"><span class="returnvalue">GCancellable</span></a> *      g_cancellable_new                   (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
<p>
Creates a new <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> object.
</p>
<p>
Applications that want to start one or more operations
that should be cancellable should create a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a>
and pass it to the operations.
</p>
<p>
One <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> can be used in multiple consecutive
operations or in multiple concurrent operations.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a>.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-cancellable-is-cancelled"></a><h3>g_cancellable_is_cancelled ()</h3>
<pre class="programlisting"><a href="./../glib/glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            g_cancellable_is_cancelled          (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>);</pre>
<p>
Checks if a cancellable job has been cancelled.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
<td>a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> or <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span>
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>
<a href="./../glib/glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>cancellable</code></em> is cancelled,
FALSE if called with <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> or if item is not cancelled.</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-cancellable-set-error-if-cancelled"></a><h3>g_cancellable_set_error_if_cancelled ()</h3>
<pre class="programlisting"><a href="./../glib/glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            g_cancellable_set_error_if_cancelled
                                                        (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>,
                                                         <em class="parameter"><code><a href="./../glib/glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre>
<p>
If the <em class="parameter"><code>cancellable</code></em> is cancelled, sets the error to notify
that the operation was cancelled.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
<td>a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> or <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
<td>
<a href="./../glib/glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> to append error state to</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>
<a href="./../glib/glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>cancellable</code></em> was cancelled, <a href="./../glib/glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> if it was not</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-cancellable-get-fd"></a><h3>g_cancellable_get_fd ()</h3>
<pre class="programlisting"><span class="returnvalue">int</span>                 g_cancellable_get_fd                (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>);</pre>
<p>
Gets the file descriptor for a cancellable job. This can be used to
implement cancellable operations on Unix systems. The returned fd will
turn readable when <em class="parameter"><code>cancellable</code></em> is cancelled.
</p>
<p>
You are not supposed to read from the fd yourself, just check for
readable status. Reading to unset the readable status is done
with <a class="link" href="GCancellable.html#g-cancellable-reset" title="g_cancellable_reset ()"><code class="function">g_cancellable_reset()</code></a>.
</p>
<p>
After a successful return from this function, you should use 
<a class="link" href="GCancellable.html#g-cancellable-release-fd" title="g_cancellable_release_fd ()"><code class="function">g_cancellable_release_fd()</code></a> to free up resources allocated for 
the returned file descriptor.
</p>
<p>
See also <a class="link" href="GCancellable.html#g-cancellable-make-pollfd" title="g_cancellable_make_pollfd ()"><code class="function">g_cancellable_make_pollfd()</code></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
<td>a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a>.</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>A valid file descriptor. <code class="literal">-1</code> if the file descriptor
is not supported, or on errors.</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-cancellable-make-pollfd"></a><h3>g_cancellable_make_pollfd ()</h3>
<pre class="programlisting"><a href="./../glib/glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            g_cancellable_make_pollfd           (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>,
                                                         <em class="parameter"><code><a href="./../glib/glib/glib-The-Main-Event-Loop.html#GPollFD"><span class="type">GPollFD</span></a> *pollfd</code></em>);</pre>
<p>
Creates a <a href="./../glib/glib/glib-The-Main-Event-Loop.html#GPollFD"><span class="type">GPollFD</span></a> corresponding to <em class="parameter"><code>cancellable</code></em>; this can be passed
to <a href="./../glib/glib/glib-The-Main-Event-Loop.html#g-poll"><code class="function">g_poll()</code></a> and used to poll for cancellation. This is useful both
for unix systems without a native poll and for portability to
windows.
</p>
<p>
When this function returns <a href="./../glib/glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a>, you should use 
<a class="link" href="GCancellable.html#g-cancellable-release-fd" title="g_cancellable_release_fd ()"><code class="function">g_cancellable_release_fd()</code></a> to free up resources allocated for the 
<em class="parameter"><code>pollfd</code></em>. After a <a href="./../glib/glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> return, do not call <a class="link" href="GCancellable.html#g-cancellable-release-fd" title="g_cancellable_release_fd ()"><code class="function">g_cancellable_release_fd()</code></a>.
</p>
<p>
If this function returns <a href="./../glib/glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a>, either no <em class="parameter"><code>cancellable</code></em> was given or
resource limits prevent this function from allocating the necessary 
structures for polling. (On Linux, you will likely have reached 
the maximum number of file descriptors.) The suggested way to handle
these cases is to ignore the <em class="parameter"><code>cancellable</code></em>.
</p>
<p>
You are not supposed to read from the fd yourself, just check for
readable status. Reading to unset the readable status is done
with <a class="link" href="GCancellable.html#g-cancellable-reset" title="g_cancellable_reset ()"><code class="function">g_cancellable_reset()</code></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
<td>a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> or <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>pollfd</code></em> :</span></p></td>
<td>a pointer to a <a href="./../glib/glib/glib-The-Main-Event-Loop.html#GPollFD"><span class="type">GPollFD</span></a>
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>
<a href="./../glib/glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>pollfd</code></em> was successfully initialized, <a href="./../glib/glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> on
failure to prepare the cancellable.</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.22</p>
</div>
<hr>
<div class="refsect2">
<a name="g-cancellable-release-fd"></a><h3>g_cancellable_release_fd ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_cancellable_release_fd            (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>);</pre>
<p>
Releases a resources previously allocated by <a class="link" href="GCancellable.html#g-cancellable-get-fd" title="g_cancellable_get_fd ()"><code class="function">g_cancellable_get_fd()</code></a>
or <a class="link" href="GCancellable.html#g-cancellable-make-pollfd" title="g_cancellable_make_pollfd ()"><code class="function">g_cancellable_make_pollfd()</code></a>.
</p>
<p>
For compatibility reasons with older releases, calling this function 
is not strictly required, the resources will be automatically freed
when the <em class="parameter"><code>cancellable</code></em> is finalized. However, the <em class="parameter"><code>cancellable</code></em> will
block scarce file descriptors until it is finalized if this function
is not called. This can cause the application to run out of file 
descriptors when many <a href="GCancellable.html"><span class="type">GCancellables</span></a> are used at the same time.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
<td>a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a>
</td>
</tr></tbody>
</table></div>
<p class="since">Since 2.22</p>
</div>
<hr>
<div class="refsect2">
<a name="g-cancellable-source-new"></a><h3>g_cancellable_source_new ()</h3>
<pre class="programlisting"><a href="./../glib/glib/glib-The-Main-Event-Loop.html#GSource"><span class="returnvalue">GSource</span></a> *           g_cancellable_source_new            (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>);</pre>
<p>
Creates a source that triggers if <em class="parameter"><code>cancellable</code></em> is cancelled and
calls its callback of type <a class="link" href="GCancellable.html#GCancellableSourceFunc" title="GCancellableSourceFunc ()"><span class="type">GCancellableSourceFunc</span></a>. This is
primarily useful for attaching to another (non-cancellable) source
with <a href="./../glib/glib/glib-The-Main-Event-Loop.html#g-source-add-child-source"><code class="function">g_source_add_child_source()</code></a> to add cancellability to it.
</p>
<p>
For convenience, you can call this with a <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a>,
in which case the source will never trigger.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
<td>a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a>, or <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>the new <a href="./../glib/glib/glib-The-Main-Event-Loop.html#GSource"><span class="type">GSource</span></a>. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.28</p>
</div>
<hr>
<div class="refsect2">
<a name="GCancellableSourceFunc"></a><h3>GCancellableSourceFunc ()</h3>
<pre class="programlisting"><a href="./../glib/glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            (*GCancellableSourceFunc)           (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>,
                                                         <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre>
<p>
This is the function type of the callback used for the <a href="./../glib/glib/glib-The-Main-Event-Loop.html#GSource"><span class="type">GSource</span></a>
returned by <a class="link" href="GCancellable.html#g-cancellable-source-new" title="g_cancellable_source_new ()"><code class="function">g_cancellable_source_new()</code></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
<td>the <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
<td>data passed in by the user.</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>it should return <a href="./../glib/glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> if the source should be removed.</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.28</p>
</div>
<hr>
<div class="refsect2">
<a name="g-cancellable-get-current"></a><h3>g_cancellable_get_current ()</h3>
<pre class="programlisting"><a class="link" href="GCancellable.html" title="GCancellable"><span class="returnvalue">GCancellable</span></a> *      g_cancellable_get_current           (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
<p>
Gets the top cancellable from the stack.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> from the top of the stack, or <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>
if the stack is empty. <span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span>
</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-cancellable-pop-current"></a><h3>g_cancellable_pop_current ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_cancellable_pop_current           (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>);</pre>
<p>
Pops <em class="parameter"><code>cancellable</code></em> off the cancellable stack (verifying that <em class="parameter"><code>cancellable</code></em>
is on the top of the stack).
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
<td>a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> object</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-cancellable-push-current"></a><h3>g_cancellable_push_current ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_cancellable_push_current          (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>);</pre>
<p>
Pushes <em class="parameter"><code>cancellable</code></em> onto the cancellable stack. The current
cancellable can then be received using <a class="link" href="GCancellable.html#g-cancellable-get-current" title="g_cancellable_get_current ()"><code class="function">g_cancellable_get_current()</code></a>.
</p>
<p>
This is useful when implementing cancellable operations in
code that does not allow you to pass down the cancellable object.
</p>
<p>
This is typically called automatically by e.g. <a class="link" href="GFile.html" title="GFile"><span class="type">GFile</span></a> operations,
so you rarely have to call this yourself.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
<td>a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> object</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-cancellable-reset"></a><h3>g_cancellable_reset ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_cancellable_reset                 (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>);</pre>
<p>
Resets <em class="parameter"><code>cancellable</code></em> to its uncancelled state.
</p>
<p>
If cancellable is currently in use by any cancellable operation
then the behavior of this function is undefined.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
<td>a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> object.</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-cancellable-connect"></a><h3>g_cancellable_connect ()</h3>
<pre class="programlisting"><a href="./../glib/glib/glib-Basic-Types.html#gulong"><span class="returnvalue">gulong</span></a>              g_cancellable_connect               (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>,
                                                         <em class="parameter"><code><a href="./../gobject/gobject/gobject-Closures.html#GCallback"><span class="type">GCallback</span></a> callback</code></em>,
                                                         <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>,
                                                         <em class="parameter"><code><a href="./../glib/glib/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> data_destroy_func</code></em>);</pre>
<p>
Convenience function to connect to the <a class="link" href="GCancellable.html#GCancellable-cancelled" title='The "cancelled" signal'><span class="type">"cancelled"</span></a>
signal. Also handles the race condition that may happen
if the cancellable is cancelled right before connecting.
</p>
<p>
<em class="parameter"><code>callback</code></em> is called at most once, either directly at the
time of the connect if <em class="parameter"><code>cancellable</code></em> is already cancelled,
or when <em class="parameter"><code>cancellable</code></em> is cancelled in some thread.
</p>
<p>
<em class="parameter"><code>data_destroy_func</code></em> will be called when the handler is
disconnected, or immediately if the cancellable is already
cancelled.
</p>
<p>
See <a class="link" href="GCancellable.html#GCancellable-cancelled" title='The "cancelled" signal'><span class="type">"cancelled"</span></a> for details on how to use this.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
<td>A <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a>.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>callback</code></em> :</span></p></td>
<td>The <a href="./../gobject/gobject/gobject-Closures.html#GCallback"><span class="type">GCallback</span></a> to connect.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
<td>Data to pass to <em class="parameter"><code>callback</code></em>.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>data_destroy_func</code></em> :</span></p></td>
<td>Free function for <em class="parameter"><code>data</code></em> or <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>The id of the signal handler or 0 if <em class="parameter"><code>cancellable</code></em> has already
been cancelled.</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.22</p>
</div>
<hr>
<div class="refsect2">
<a name="g-cancellable-disconnect"></a><h3>g_cancellable_disconnect ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_cancellable_disconnect            (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>,
                                                         <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gulong"><span class="type">gulong</span></a> handler_id</code></em>);</pre>
<p>
Disconnects a handler from a cancellable instance similar to
<a href="./../gobject/gobject/gobject-Signals.html#g-signal-handler-disconnect"><code class="function">g_signal_handler_disconnect()</code></a>.  Additionally, in the event that a
signal handler is currently running, this call will block until the
handler has finished.  Calling this function from a
<a class="link" href="GCancellable.html#GCancellable-cancelled" title='The "cancelled" signal'><span class="type">"cancelled"</span></a> signal handler will therefore result in a
deadlock.
</p>
<p>
This avoids a race condition where a thread cancels at the
same time as the cancellable operation is finished and the
signal handler is removed. See <a class="link" href="GCancellable.html#GCancellable-cancelled" title='The "cancelled" signal'><span class="type">"cancelled"</span></a> for
details on how to use this.
</p>
<p>
If <em class="parameter"><code>cancellable</code></em> is <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> or <em class="parameter"><code>handler_id</code></em> is <code class="literal">0</code> this function does
nothing.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
<td>A <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> or <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>handler_id</code></em> :</span></p></td>
<td>Handler id of the handler to be disconnected, or <code class="literal">0</code>.</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.22</p>
</div>
<hr>
<div class="refsect2">
<a name="g-cancellable-cancel"></a><h3>g_cancellable_cancel ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_cancellable_cancel                (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>);</pre>
<p>
Will set <em class="parameter"><code>cancellable</code></em> to cancelled, and will emit the
<a class="link" href="GCancellable.html#GCancellable-cancelled" title='The "cancelled" signal'><span class="type">"cancelled"</span></a> signal. (However, see the warning about
race conditions in the documentation for that signal if you are
planning to connect to it.)
</p>
<p>
This function is thread-safe. In other words, you can safely call
it from a thread other than the one running the operation that was
passed the <em class="parameter"><code>cancellable</code></em>.
</p>
<p>
The convention within gio is that cancelling an asynchronous
operation causes it to complete asynchronously. That is, if you
cancel the operation from the same thread in which it is running,
then the operation's <a class="link" href="GAsyncResult.html#GAsyncReadyCallback" title="GAsyncReadyCallback ()"><span class="type">GAsyncReadyCallback</span></a> will not be invoked until
the application returns to the main loop.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
<td>a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> object.</td>
</tr></tbody>
</table></div>
</div>
</div>
<div class="refsect1">
<a name="GCancellable.signal-details"></a><h2>Signal Details</h2>
<div class="refsect2">
<a name="GCancellable-cancelled"></a><h3>The <code class="literal">"cancelled"</code> signal</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                user_function                      (<a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable,
                                                        <a href="./../glib/glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a>      user_data)        : <a href="./../gobject/gobject/gobject-Signals.html#G-SIGNAL-RUN-LAST:CAPS"><code class="literal">Run Last</code></a></pre>
<p>
Emitted when the operation has been cancelled.
</p>
<p>
Can be used by implementations of cancellable operations. If the
operation is cancelled from another thread, the signal will be
emitted in the thread that cancelled the operation, not the
thread that is running the operation.
</p>
<p>
Note that disconnecting from this signal (or any signal) in a
multi-threaded program is prone to race conditions. For instance
it is possible that a signal handler may be invoked even
<span class="emphasis"><em>after</em></span> a call to
<a href="./../gobject/gobject/gobject-Signals.html#g-signal-handler-disconnect"><code class="function">g_signal_handler_disconnect()</code></a> for that handler has already
returned.
</p>
<p>
There is also a problem when cancellation happen
right before connecting to the signal. If this happens the
signal will unexpectedly not be emitted, and checking before
connecting to the signal leaves a race condition where this is
still happening.
</p>
<p>
In order to make it safe and easy to connect handlers there
are two helper functions: <a class="link" href="GCancellable.html#g-cancellable-connect" title="g_cancellable_connect ()"><code class="function">g_cancellable_connect()</code></a> and
<a class="link" href="GCancellable.html#g-cancellable-disconnect" title="g_cancellable_disconnect ()"><code class="function">g_cancellable_disconnect()</code></a> which protect against problems
like this.
</p>
<p>
An example of how to us this:
</p>
<div class="informalexample">
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    <tbody>
      <tr>
        <td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20</pre></td>
        <td class="listing_code"><pre class="programlisting"><span class="comment">/* Make sure we don't do any unnecessary work if already cancelled */</span>
<span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="function"><a href="GCancellable.html#g-cancellable-set-error-if-cancelled">g_cancellable_set_error_if_cancelled</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">cancellable</span><span class="symbol">))</span>
<span class="normal">  </span><span class="keyword">return</span><span class="symbol">;</span>
<span class="comment">/* Set up all the data needed to be able to</span>
<span class="comment"> * handle cancellation of the operation */</span>
<span class="normal">my_data </span><span class="symbol">=</span><span class="normal"> </span><span class="function">my_data_new</span><span class="normal"> </span><span class="symbol">(...);</span>

<span class="normal">id </span><span class="symbol">=</span><span class="normal"> </span><span class="number">0</span><span class="symbol">;</span>
<span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">cancellable</span><span class="symbol">)</span>
<span class="normal">  id </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="GCancellable.html#g-cancellable-connect">g_cancellable_connect</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">cancellable</span><span class="symbol">,</span>
<span class="normal">                  </span><span class="function"><a href="./../gobject/gobject/gobject-Closures.html#G-CALLBACK:CAPS">G_CALLBACK</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">cancelled_handler</span><span class="symbol">)</span>
<span class="normal">                  data</span><span class="symbol">,</span><span class="normal"> <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span>

<span class="comment">/* cancellable operation here... */</span>

<span class="function"><a href="GCancellable.html#g-cancellable-disconnect">g_cancellable_disconnect</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">cancellable</span><span class="symbol">,</span><span class="normal"> id</span><span class="symbol">);</span>

<span class="comment">/* cancelled_handler is never called after this, it</span>
<span class="comment"> * is now safe to free the data */</span>
<span class="function">my_data_free</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">my_data</span><span class="symbol">);</span></pre></td>
      </tr>
    </tbody>
  </table>
</div>

<p>
</p>
<p>
Note that the cancelled signal is emitted in the thread that
the user cancelled from, which may be the main thread. So, the
cancellable signal should not do something that can block.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
<td>a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a>.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
<td>user data set when the signal handler was connected.</td>
</tr>
</tbody>
</table></div>
</div>
</div>
</div>
<div class="footer">
<hr>
          Generated by GTK-Doc V1.17</div>
</body>
</html>